<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "https://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<meta name="generator" content="Doxygen 1.8.17"/>
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<title>BadgerDB: BadgerDB Documentation</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<link href="search/search.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="search/searchdata.js"></script>
<script type="text/javascript" src="search/search.js"></script>
<link href="doxygen.css" rel="stylesheet" type="text/css" />
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
 <tbody>
 <tr style="height: 56px;">
  <td id="projectalign" style="padding-left: 0.5em;">
   <div id="projectname">BadgerDB
   </div>
  </td>
 </tr>
 </tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.8.17 -->
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:cf05388f2679ee054f2beb29a391d25f4e673ac3&amp;dn=gpl-2.0.txt GPL-v2 */
var searchBox = new SearchBox("searchBox", "search",false,'Search');
/* @license-end */
</script>
<script type="text/javascript" src="menudata.js"></script>
<script type="text/javascript" src="menu.js"></script>
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:cf05388f2679ee054f2beb29a391d25f4e673ac3&amp;dn=gpl-2.0.txt GPL-v2 */
$(function() {
  initMenu('',true,false,'search.php','Search');
  $(document).ready(function() { init_search(); });
});
/* @license-end */</script>
<div id="main-nav"></div>
</div><!-- top -->
<!-- window showing the filter options -->
<div id="MSearchSelectWindow"
     onmouseover="return searchBox.OnSearchSelectShow()"
     onmouseout="return searchBox.OnSearchSelectHide()"
     onkeydown="return searchBox.OnSearchSelectKey(event)">
</div>

<!-- iframe showing the search results (closed by default) -->
<div id="MSearchResultsWindow">
<iframe src="javascript:void(0)" frameborder="0" 
        name="MSearchResults" id="MSearchResults">
</iframe>
</div>

<div class="PageDoc"><div class="header">
  <div class="headertitle">
<div class="title">BadgerDB Documentation </div>  </div>
</div><!--header-->
<div class="contents">
<div class="textblock"><h1><a class="anchor" id="toc_sec"></a>
Table of contents</h1>
<ol>
<li>
<a class="el" href="index.html#file_layout_sec">File layout</a> </li>
<li>
<a class="el" href="index.html#building_sec">Building and modifying the system</a> <ol>
<li>
<a class="el" href="index.html#prereq_sec">Prerequisites</a> </li>
<li>
<a class="el" href="index.html#commands_sec">Executing a build</a> </li>
<li>
<a class="el" href="index.html#modify_run_main_sec">Modifying and running main</a> </li>
<li>
<a class="el" href="index.html#documentation_sec">Rebuilding the documentation</a> </li>
</ol>
</li>
<li>
<a class="el" href="index.html#api_sec">BadgerDB API</a> <ol>
<li>
<a class="el" href="index.html#storage_sec">File storage</a> <ol>
<li>
<a class="el" href="index.html#file_management_sec">Creating, opening, and deleting files</a> </li>
<li>
<a class="el" href="index.html#file_data_sec">Reading and writing data in a file</a> </li>
<li>
<a class="el" href="index.html#page_sec">Reading and writing data in a page</a> </li>
</ol>
</li>
</ol>
</li>
</ol>
<h1><a class="anchor" id="file_layout_sec"></a>
File layout</h1>
<p>The files in this package are organized under the following hierarchy: </p><pre>
docs/                  generated documentation
src/                   code for BadgerDB
</pre><p>You will likely be most interested in <code>src</code></p>
<h1><a class="anchor" id="building_sec"></a>
Building and modifying the system</h1>
<h2><a class="anchor" id="prereq_sec"></a>
Prerequisites</h2>
<p>To build and run the system, you need the following packages: </p><ul>
<li>
A modern C++ compiler (GCC &gt;= 4.6, any recent version of clang) </li>
<li>
Doxygen 1.6 or higher (for generating documentation only) </li>
</ul>
<p>The build system is configured to work on CSL RedHat 5 and 6 machines out of the box.</p>
<h2><a class="anchor" id="commands_sec"></a>
Executing a build</h2>
<p>All command examples are meant to be run at the command prompt from the <code>badgerdb</code> directory. When executing a command, omit the <code>$</code> prompt (so &ldquo;<code>$ make</code>&rdquo; means you just type &ldquo;<code>make</code>&rdquo; and press enter).</p>
<p>To build the executable: </p><div class="fragment"><div class="line">$ make</div>
</div><!-- fragment --><h2><a class="anchor" id="modify_run_main_sec"></a>
Modifying and running main</h2>
<p>To run the executable, first build the code, then run: </p><div class="fragment"><div class="line">$ ./src/badgerdb_main</div>
</div><!-- fragment --><p>If you want to edit what <code>badgerdb_main</code> does, edit <code><a class="el" href="main_8cpp_source.html">src/main.cpp</a></code>.</p>
<h2><a class="anchor" id="documentation_sec"></a>
Rebuilding the documentation</h2>
<p>Documentation is generated by using Doxygen. If you have updated the documentation and need to regenerate the output files, run: </p><div class="fragment"><div class="line">$ make doc</div>
</div><!-- fragment --><p> Resulting documentation will be placed in the <code>docs/</code> directory; open <code>index.html</code> with your web browser to view it.</p>
<h1><a class="anchor" id="api_sec"></a>
BadgerDB API</h1>
<h2><a class="anchor" id="storage_sec"></a>
File storage</h2>
<p>Interaction with the underlying filesystem is handled by two classes: File and Page. Files store zero or more fixed-length pages; each page holds zero or more variable-length records.</p>
<p>Record data is represented using std::strings of arbitrary characters.</p>
<h3><a class="anchor" id="file_management_sec"></a>
Creating, opening, and deleting files</h3>
<p>Files must first be created before they can be used: </p><div class="fragment"><div class="line"><span class="comment">// Create and open a new file with the name &quot;filename.db&quot;.</span></div>
<div class="line"><a class="code" href="classbadgerdb_1_1_file.html">badgerdb::File</a> new_file = <a class="code" href="classbadgerdb_1_1_file.html#a1fb708b45103a606f189850d6bf83a0c">badgerdb::File::create</a>(<span class="stringliteral">&quot;filename.db&quot;</span>);</div>
</div><!-- fragment --><p>If you want to open an existing file, use File::open like so: </p><div class="fragment"><div class="line"><span class="comment">// Open an existing file with the name &quot;filename.db&quot;.</span></div>
<div class="line"><a class="code" href="classbadgerdb_1_1_file.html">badgerdb::File</a> existing_file = <a class="code" href="classbadgerdb_1_1_file.html#a8462afdbd250c0a483ddfbde144c8732">badgerdb::File::open</a>(<span class="stringliteral">&quot;filename.db&quot;</span>);</div>
</div><!-- fragment --><p>Multiple File objects share the same stream to the underlying file. The stream will be automatically closed when the last File object is out of scope; no explicit close command is necessary.</p>
<p>You can delete a file with File::remove: </p><div class="fragment"><div class="line"><span class="comment">// Delete a file with the name &quot;filename.db&quot;.</span></div>
<div class="line"><a class="code" href="classbadgerdb_1_1_file.html#a1cc69467366badbd68021ac76a91190e">badgerdb::File::remove</a>(<span class="stringliteral">&quot;filename.db&quot;</span>);</div>
</div><!-- fragment --><h3><a class="anchor" id="file_data_sec"></a>
Reading and writing data in a file</h3>
<p>Data is added to a File by first allocating a Page, populating it with data, and then writing the Page back to the File.</p>
<p>For example: </p><div class="fragment"><div class="line"><span class="preprocessor">#include &quot;file.h&quot;</span></div>
<div class="line"> </div>
<div class="line">...</div>
<div class="line"> </div>
<div class="line"><span class="comment">// Write a record with the value &quot;hello, world!&quot; to the file.</span></div>
<div class="line">badgerdb::File db_file = <a class="code" href="classbadgerdb_1_1_file.html#a8462afdbd250c0a483ddfbde144c8732">badgerdb::File::open</a>(<span class="stringliteral">&quot;filename.db&quot;</span>);</div>
<div class="line"><a class="code" href="classbadgerdb_1_1_page.html">badgerdb::Page</a> new_page = db_file.allocatePage();</div>
<div class="line">new_page.<a class="code" href="classbadgerdb_1_1_page.html#ad0b1e85fe7849fb767dd8c21a8053cf4">insertRecord</a>(<span class="stringliteral">&quot;hello, world!&quot;</span>);</div>
<div class="line">db_file.writePage(new_page);</div>
</div><!-- fragment --><p>Pages are read back from a File using their page numbers: </p><div class="fragment"><div class="line"><span class="preprocessor">#include &quot;file.h&quot;</span></div>
<div class="line"><span class="preprocessor">#include &quot;page.h&quot;</span></div>
<div class="line"> </div>
<div class="line">...</div>
<div class="line"> </div>
<div class="line"><span class="comment">// Allocate a page and then read it back.</span></div>
<div class="line">badgerdb::Page new_page = db_file.allocatePage();</div>
<div class="line">db_file.writePage(new_page);</div>
<div class="line"><span class="keyword">const</span> <a class="code" href="namespacebadgerdb.html#a1f49e404293bf4240756b89b53b1587a">badgerdb::PageId</a>&amp; page_number = new_page.<a class="code" href="classbadgerdb_1_1_page.html#af8416fd0be779f473c97b47e797e1c53">page_number</a>();</div>
<div class="line"><a class="code" href="classbadgerdb_1_1_page.html">badgerdb::Page</a> same_page = db_file.readPage(page_number);</div>
</div><!-- fragment --><p>You can also iterate through all pages in the File: </p><div class="fragment"><div class="line"><span class="preprocessor">#include &quot;file_iterator.h&quot;</span></div>
<div class="line"> </div>
<div class="line">...</div>
<div class="line"> </div>
<div class="line">for (<a class="code" href="classbadgerdb_1_1_file_iterator.html">badgerdb::FileIterator</a> iter = db_file.begin();</div>
<div class="line">     iter != db_file.end();</div>
<div class="line">     ++iter) {</div>
<div class="line">  std::cout &lt;&lt; <span class="stringliteral">&quot;Read page: &quot;</span> &lt;&lt; iter-&gt;page_number() &lt;&lt; std::endl;</div>
<div class="line">}</div>
</div><!-- fragment --><h3><a class="anchor" id="page_sec"></a>
Reading and writing data in a page</h3>
<p>Pages hold variable-length records containing arbitrary data.</p>
<p>To insert data on a page: </p><div class="fragment"><div class="line"><span class="preprocessor">#include &quot;page.h&quot;</span></div>
<div class="line"> </div>
<div class="line">...</div>
<div class="line"> </div>
<div class="line">badgerdb::Page new_page;</div>
<div class="line">new_page.<a class="code" href="classbadgerdb_1_1_page.html#ad0b1e85fe7849fb767dd8c21a8053cf4">insertRecord</a>(<span class="stringliteral">&quot;hello, world!&quot;</span>);</div>
</div><!-- fragment --><p>Data is read by using RecordIds, which are provided when data is inserted: </p><div class="fragment"><div class="line"><span class="preprocessor">#include &quot;page.h&quot;</span></div>
<div class="line"> </div>
<div class="line">...</div>
<div class="line"> </div>
<div class="line">badgerdb::Page new_page;</div>
<div class="line"><span class="keyword">const</span> <a class="code" href="structbadgerdb_1_1_record_id.html">badgerdb::RecordId</a>&amp; rid = new_page.<a class="code" href="classbadgerdb_1_1_page.html#ad0b1e85fe7849fb767dd8c21a8053cf4">insertRecord</a>(<span class="stringliteral">&quot;hello, world!&quot;</span>);</div>
<div class="line">new_page.<a class="code" href="classbadgerdb_1_1_page.html#aad81fa59b469866fbd260c8a640b579f">getRecord</a>(rid); <span class="comment">// returns &quot;hello, world!&quot;</span></div>
</div><!-- fragment --><p>As Pages use std::string to represent data, it's very natural to insert strings; however, any data can be stored: </p><div class="fragment"><div class="line"><span class="preprocessor">#include &quot;page.h&quot;</span></div>
<div class="line"> </div>
<div class="line">...</div>
<div class="line"> </div>
<div class="line">struct Point {</div>
<div class="line">  <span class="keywordtype">int</span> x;</div>
<div class="line">  <span class="keywordtype">int</span> y;</div>
<div class="line">};</div>
<div class="line">Point new_point = {10, -5};</div>
<div class="line"><a class="code" href="classbadgerdb_1_1_page.html">badgerdb::Page</a> new_page;</div>
<div class="line">std::string new_data(<span class="keyword">reinterpret_cast&lt;</span><span class="keywordtype">char</span>*<span class="keyword">&gt;</span>(&amp;new_point),</div>
<div class="line">                     <span class="keyword">sizeof</span>(new_point));</div>
<div class="line"><span class="keyword">const</span> <a class="code" href="structbadgerdb_1_1_record_id.html">badgerdb::RecordId</a>&amp; rid = new_page.<a class="code" href="classbadgerdb_1_1_page.html#ad0b1e85fe7849fb767dd8c21a8053cf4">insertRecord</a>(new_data);</div>
<div class="line">Point read_point =</div>
<div class="line">    *<span class="keyword">reinterpret_cast&lt;</span><span class="keyword">const </span>Point*<span class="keyword">&gt;</span>(new_page.<a class="code" href="classbadgerdb_1_1_page.html#aad81fa59b469866fbd260c8a640b579f">getRecord</a>(rid).data());</div>
</div><!-- fragment --><p> Note that serializing structures like this is not industrial strength; it's better to use something like Google's protocol buffers or Boost serialization.</p>
<p>You can also iterate through all records in the Page: </p><div class="fragment"><div class="line"><span class="preprocessor">#include &quot;page_iterator.h&quot;</span></div>
<div class="line"> </div>
<div class="line">...</div>
<div class="line"> </div>
<div class="line">for (<a class="code" href="classbadgerdb_1_1_page_iterator.html">badgerdb::PageIterator</a> iter = new_page.<a class="code" href="classbadgerdb_1_1_page.html#aa0fdb281074cd60cb1f1d6ea6d620772">begin</a>();</div>
<div class="line">     iter != new_page.<a class="code" href="classbadgerdb_1_1_page.html#a8e78cba69bef682a5427932485da4608">end</a>();</div>
<div class="line">     ++iter) {</div>
<div class="line">  std::cout &lt;&lt; <span class="stringliteral">&quot;Record data: &quot;</span> &lt;&lt; *iter &lt;&lt; std::endl;</div>
<div class="line">}</div>
</div><!-- fragment --> </div></div><!-- PageDoc -->
</div><!-- contents -->
<div class="ttc" id="aclassbadgerdb_1_1_file_html_a8462afdbd250c0a483ddfbde144c8732"><div class="ttname"><a href="classbadgerdb_1_1_file.html#a8462afdbd250c0a483ddfbde144c8732">badgerdb::File::open</a></div><div class="ttdeci">static File open(const std::string &amp;filename)</div><div class="ttdef"><b>Definition:</b> <a href="file_8cpp_source.html#l00033">file.cpp:33</a></div></div>
<div class="ttc" id="aclassbadgerdb_1_1_file_html_a1fb708b45103a606f189850d6bf83a0c"><div class="ttname"><a href="classbadgerdb_1_1_file.html#a1fb708b45103a606f189850d6bf83a0c">badgerdb::File::create</a></div><div class="ttdeci">static File create(const std::string &amp;filename)</div><div class="ttdef"><b>Definition:</b> <a href="file_8cpp_source.html#l00029">file.cpp:29</a></div></div>
<div class="ttc" id="aclassbadgerdb_1_1_page_html_ad0b1e85fe7849fb767dd8c21a8053cf4"><div class="ttname"><a href="classbadgerdb_1_1_page.html#ad0b1e85fe7849fb767dd8c21a8053cf4">badgerdb::Page::insertRecord</a></div><div class="ttdeci">RecordId insertRecord(const std::string &amp;record_data)</div><div class="ttdef"><b>Definition:</b> <a href="page_8cpp_source.html#l00033">page.cpp:33</a></div></div>
<div class="ttc" id="astructbadgerdb_1_1_record_id_html"><div class="ttname"><a href="structbadgerdb_1_1_record_id.html">badgerdb::RecordId</a></div><div class="ttdoc">Identifier for a record in a page.</div><div class="ttdef"><b>Definition:</b> <a href="types_8h_source.html#l00030">types.h:30</a></div></div>
<div class="ttc" id="aclassbadgerdb_1_1_file_html_a1cc69467366badbd68021ac76a91190e"><div class="ttname"><a href="classbadgerdb_1_1_file.html#a1cc69467366badbd68021ac76a91190e">badgerdb::File::remove</a></div><div class="ttdeci">static void remove(const std::string &amp;filename)</div><div class="ttdef"><b>Definition:</b> <a href="file_8cpp_source.html#l00037">file.cpp:37</a></div></div>
<div class="ttc" id="aclassbadgerdb_1_1_page_html_aa0fdb281074cd60cb1f1d6ea6d620772"><div class="ttname"><a href="classbadgerdb_1_1_page.html#aa0fdb281074cd60cb1f1d6ea6d620772">badgerdb::Page::begin</a></div><div class="ttdeci">PageIterator begin()</div><div class="ttdef"><b>Definition:</b> <a href="page_8cpp_source.html#l00196">page.cpp:196</a></div></div>
<div class="ttc" id="aclassbadgerdb_1_1_page_html_af8416fd0be779f473c97b47e797e1c53"><div class="ttname"><a href="classbadgerdb_1_1_page.html#af8416fd0be779f473c97b47e797e1c53">badgerdb::Page::page_number</a></div><div class="ttdeci">PageId page_number() const</div><div class="ttdef"><b>Definition:</b> <a href="page_8h_source.html#l00193">page.h:193</a></div></div>
<div class="ttc" id="aclassbadgerdb_1_1_file_html"><div class="ttname"><a href="classbadgerdb_1_1_file.html">badgerdb::File</a></div><div class="ttdoc">Class which represents a file in the filesystem containing database pages.</div><div class="ttdef"><b>Definition:</b> <a href="file_8h_source.html#l00073">file.h:73</a></div></div>
<div class="ttc" id="anamespacebadgerdb_html_a1f49e404293bf4240756b89b53b1587a"><div class="ttname"><a href="namespacebadgerdb.html#a1f49e404293bf4240756b89b53b1587a">badgerdb::PageId</a></div><div class="ttdeci">std::uint32_t PageId</div><div class="ttdoc">Identifier for a page in a file.</div><div class="ttdef"><b>Definition:</b> <a href="types_8h_source.html#l00015">types.h:15</a></div></div>
<div class="ttc" id="aclassbadgerdb_1_1_page_html"><div class="ttname"><a href="classbadgerdb_1_1_page.html">badgerdb::Page</a></div><div class="ttdoc">Class which represents a fixed-size database page containing records.</div><div class="ttdef"><b>Definition:</b> <a href="page_8h_source.html#l00107">page.h:107</a></div></div>
<div class="ttc" id="aclassbadgerdb_1_1_page_html_aad81fa59b469866fbd260c8a640b579f"><div class="ttname"><a href="classbadgerdb_1_1_page.html#aad81fa59b469866fbd260c8a640b579f">badgerdb::Page::getRecord</a></div><div class="ttdeci">std::string getRecord(const RecordId &amp;record_id) const</div><div class="ttdef"><b>Definition:</b> <a href="page_8cpp_source.html#l00043">page.cpp:43</a></div></div>
<div class="ttc" id="aclassbadgerdb_1_1_page_iterator_html"><div class="ttname"><a href="classbadgerdb_1_1_page_iterator.html">badgerdb::PageIterator</a></div><div class="ttdoc">Iterator for iterating over the records in a page.</div><div class="ttdef"><b>Definition:</b> <a href="page__iterator_8h_source.html#l00023">page_iterator.h:23</a></div></div>
<div class="ttc" id="aclassbadgerdb_1_1_page_html_a8e78cba69bef682a5427932485da4608"><div class="ttname"><a href="classbadgerdb_1_1_page.html#a8e78cba69bef682a5427932485da4608">badgerdb::Page::end</a></div><div class="ttdeci">PageIterator end()</div><div class="ttdef"><b>Definition:</b> <a href="page_8cpp_source.html#l00200">page.cpp:200</a></div></div>
<div class="ttc" id="aclassbadgerdb_1_1_file_iterator_html"><div class="ttname"><a href="classbadgerdb_1_1_file_iterator.html">badgerdb::FileIterator</a></div><div class="ttdoc">Iterator for iterating over the pages in a file.</div><div class="ttdef"><b>Definition:</b> <a href="file__iterator_8h_source.html#l00023">file_iterator.h:23</a></div></div>
<!-- start footer part -->
<hr class="footer"/><address class="footer"><small>
Generated by &#160;<a href="http://www.doxygen.org/index.html">
<img class="footer" src="doxygen.png" alt="doxygen"/>
</a> 1.8.17
</small></address>
</body>
</html>
